Add FTPS with SSL/TLS configuration by YasanPunch · Pull Request #1522 · ballerina-platform/module-ballerina-ftp

YasanPunch · 2025-12-16T17:37:56Z

Purpose

Fixes: ballerina-platform/ballerina-library/#8489

Adds FTPS (FTP over SSL/TLS) support to the FTP module, enabling secure file transfers using SSL/TLS certificates and encrypted data channels.

Changes:

Added FTPS protocol option to the Protocol enum.
Added SecureSocket configuration record for FTPS SSL/TLS settings.
Added FtpsMode enum to support IMPLICIT and EXPLICIT FTPS modes.
Added FtpsDataChannelProtection enum to control data channel encryption (PROT P/C/S/E)

API Changes:

public enum Protocol {
    FTP = "ftp",
    FTPS = "ftps",  // New: Secure File Transfer Protocol
    SFTP = "sftp"
}

# FTPS connection mode
public enum FtpsMode {
    IMPLICIT,   // SSL/TLS established immediately (typically port 990)
    EXPLICIT    // Upgrades to SSL/TLS via AUTH TLS (typically port 21)
}

# FTPS data channel protection level
public enum FtpsDataChannelProtection {
    CLEAR,          // PROT C - Clear/Unencrypted data channel
    PRIVATE,        // PROT P - Encrypted data channel (Default/Recommended)
    SAFE,           // PROT S - Integrity protected
    CONFIDENTIAL    // PROT E - Confidentiality protected
}

# Secure socket configuration for FTPS
public type SecureSocket record {|
    crypto:KeyStore key?;       // Client certificate/key
    crypto:TrustStore cert?;    // Server certificate/truststore
    FtpsMode mode = EXPLICIT;
    FtpsDataChannelProtection dataChannelProtection = PRIVATE;
|};

public type AuthConfiguration record {|
    // ... existing fields ...
    SecureSocket secureSocket?;  // New: For FTPS protocol
|};

(Current) Usage Example:

ftp:ClientConfiguration ftpsConfig = {
    protocol: ftp:FTPS,
    host: "ftps.example.com",
    port: 21,
    auth: {
        credentials: {username: "user", password: "pass"},
        secureSocket: {
            key: {path: "client.p12", password: "keypass"},
            trustStore: {path: "truststore.p12", password: "trustpass"},
            mode: ftp:EXPLICIT
        }
    }
};

Usage Example

ftp:ClientConfiguration ftpsConfig = {
protocol: ftp:FTPS,
host: "ftps.example.com",
port: 21,
auth: {
credentials: {username: "user", password: "pass"},
secureSocket: {
key: {path: "client.p12", password: "keypass"},
cert: {path: "truststore.p12", password: "trustpass"},
mode: ftp:EXPLICIT,
dataChannelProtection: ftp:PRIVATE
}
}
};

Future Enhancements (TODO):

[Hostname verification toggle for enhanced security (Currently handled by default VFS/JSSE behavior).

Checklist

Linked to an issue
Updated the changelog
Added tests (Client, Listener, and Configuration tests added.)
Updated the spec
Checked native-image compatibility

…nd SSL/TLS certificate handling.

… 990 for IMPLICIT FTPS if unspecified. Improved KeyStore loading from Ballerina records and error handling for secure socket configurations.

…improved error handling for KeyStore loading, and added documentation regarding the limitations of hostname verification support.

…r implementations, as it is not supported by the current version of Apache Commons VFS2. Clean up related code and constants.

… configuration - Introduced tests for FTPS client operations including explicit and implicit modes, file handling, and error scenarios. - Added tests for FTPS listener functionality, ensuring correct event handling for file changes. - Improved error handling for secure socket configurations in both client and server implementations. - Updated mock server utilities to include FTPS server initialization for testing purposes.

… relevant files for consistency, , remove hardcoded credentials and enhance password handling for improved security.

- Refactored test structure for better isolation and clarity. - Introduced helper functions for state management and event handling. - Improved file handling in tests, ensuring robust cleanup and setup. - Updated mock server utilities to ensure isolated test environments for FTPS operations.

…ments - Introduced a new configuration for testing the default port logic, ensuring that port 21 is correctly swapped to 990 for implicit mode. - Added a cleanup function to manage test environment state after execution. - Enhanced existing test cases to validate the new configuration and ensure robust error handling during FTPS operations.

- Updated the FTPS client test to use a more descriptive variable name for error handling. - Increased the wait count in listener tests to ensure proper event detection. - Improved error message clarity for invalid truststore scenarios in tests. - Adjusted the FtpClient to default to port 990 when port 21 is specified for implicit FTPS mode.

…ing age filtering and timeout handling.

sonarqubecloud · 2025-12-16T17:38:42Z

Quality Gate passed

Issues
17 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
2.5% Duplication on New Code

See analysis details on SonarQube Cloud

Yasan and others added 30 commits December 7, 2025 14:50

[Automated] Update the native jar versions

3c059a8

added SecureSocket record for FTPS

c0f3163

[Automated] Update the native jar versions

b7147a2

Added explicit/implicit modes

c7b5f7f

used ftpsconfigbuilder from apache vfs2

457e5af

Enhance FTPS support by adding explicit/implicit mode configuration a…

c9770d8

…nd SSL/TLS certificate handling.

[Automated] Update the native jar versions

6fd9e9f

updated sftp/ftps validation

db9a99f

Added data channel protection and host verification

62a5356

fixed vfs config builder usage

e54c65c

fixed crypto:keystore integration issue

3903c6b

Enhance FTPS configuration and KeyStore handling. Default port set to…

6b9cb26

… 990 for IMPLICIT FTPS if unspecified. Improved KeyStore loading from Ballerina records and error handling for secure socket configurations.

Updated methods to directly call configuration extraction functions, …

0ab1ef0

…improved error handling for KeyStore loading, and added documentation regarding the limitations of hostname verification support.

upated gradle properties

16c12ca

Remove FTPS hostname verification configuration from client and serve…

0f73cc0

…r implementations, as it is not supported by the current version of Apache Commons VFS2. Clean up related code and constants.

[Automated] Update the native jar versions

bd1d401

initial test for ftps

670f53b

Refactor FTPS configuration: rename 'trustStore' to 'cert' across all…

1e47dc5

… relevant files for consistency, , remove hardcoded credentials and enhance password handling for improved security.

Implement onFileDeleted->onFileDelete method name change

702326f

Fix depreciation warning

5f1d525

Update spec

d126044

Update changelog

36d04e1

Fix grammer

138bb45

[Automated] Update the native jar versions

97cbb54

Upgrade task dependency

4b91caa

Add license headers

afdd8d8

Revert cron support temporality for relase

0d278a1

YasanPunch added 7 commits December 16, 2025 22:26

Remove FTPS secure publisher example files and resources

3668001

[Automated] Update the native jar versions

ab70b56

[Automated] Update the native jar versions

d757247

Add FTPS test cases for advanced configurations and validation includ…

37e9e6c

…ing age filtering and timeout handling.

[Automated] Update the native jar versions

7ba8f5a

Merge remote-tracking branch 'upstream/master' into add-ftps

95ef169

YasanPunch closed this Dec 16, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

Add FTPS with SSL/TLS configuration#1522

Add FTPS with SSL/TLS configuration#1522
YasanPunch wants to merge 37 commits intoballerina-platform:masterfrom
YasanPunch:add-ftps

YasanPunch commented Dec 16, 2025

Uh oh!

sonarqubecloud bot commented Dec 16, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments

Conversation

YasanPunch commented Dec 16, 2025

Purpose

Changes:

API Changes:

(Current) Usage Example:

Usage Example

Future Enhancements (TODO):

Checklist

Uh oh!

sonarqubecloud bot commented Dec 16, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants